home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Essential Bibles
/
Essential Bibles (1998).iso
/
DOS
/
ZIPS
/
DRC20.ZIP
/
README.SRC
< prev
next >
Wrap
Text File
|
1992-08-16
|
23KB
|
628 lines
%%*
%%* README.SRC
%%* User's guide for David's Readme Compiler v2.0
%%* (c) 1991, 1992, David Harris, all rights reserved.
%%*
%%* Compile an executable readme from this file using
%%* the command 'RCOM README.SRC'.
%%*
%%*
%%* This line is a comment.
%%* Note that because of the particular way this file is
%%* parsed, blank lines ARE significant.
%%*
%%* The next line is the title for the main screen.
%%*
%%Title 0, David's Readme Compiler v2.0 - User's Guide
%%*
%%*
%%* The next statement specifies an opening screen, which is
%%* presented to the user when the program is run.
%%*
%%Opening_screen 2000
%%*
%%* Now we'll actually declare the opening screen. For
%%* performance reasons, it should be placed as close
%%* to the start of the file as possible.
%%*
%% 2000, 0, 0, 0, 8, Welcome to David's Readme Compiler v2
David's Readme Compiler allows you to create standalone guides,
readme files, and other textual references.
Version 2 of DRC supports many new features: if you currently
use DRC v1, please examine the section "What's new in DRC v2"
on the main menu.
%%*
%%*
%%* Now we'll define a status line for the main screen:
%%*
%%Status_line 2001
%%*
%% 2001, 0, 7, Status line
David's Readme Compiler, (c) 1991, 1992, David Harris.
%%*
%%*
%%* Next, define a screen which DRC can present when the
%%* user asks to edit a topic using the <F10> menu
%%*
%%Edit_screen 2002
%%*
%% 2002, 0, 87, 87, Editing a topic
While you edit this topic, the following keys are
available for your use:
Arrows: move in the indicated direction
Ctrl-Arrows: move a word at a time
PgUp/PgDn: move a screen at a time
Tab: moves to the next field on the screen:
a field is anything starting with a
left square bracket ([). This feature
is handy for designing forms which the
user is to complete.
Ctrl-Y: delete the current line
Del, Bks: delete char right, delete char left
Ins: toggle insert mode (defaults to OFF)
%%*
%%*
%%* And lastly we'll set the default flags values for
%%* the whole script. We'll use the value 7, which indicates
%%* that the user can Edit, Save, and Print the readme screens.
%%*
%%Default_flags 7
%%*
%%*
%%* The next line is the first top-level entry in the file (note
%%* the type of 0). The second integer means that this entry leads
%%* to a sub-menu of items of type 100 in the file.
%%*
%% 0, 100, About the Readme Compiler
%%*
%%*
%%* The next entry is a top level item with no sub-entries: when
%%* selected, its associated text will display at once.
%%*
%% 0, 0, Installing the Readme Compiler
To install David's Readme Compiler, place the files
README.BIN and RCOM.EXE in a directory somewhere.
Actual location doesn't matter, so long as both are
in the same place. If you intend to use the -s switch
to RCOM to create simple readmes (ie, readmes without
extended searching and formatting features) then you
should also copy README1.BIN to the same location.
The programs can be on the path if you wish, but
they don't have to be, provided they are all in
the same directory.
%%*
%%*
%%* The next line is an index entry for items of
%%* type 300: when it is selected, all the items
%%* of type 300 in the file will be collected into
%%* a menu and displayed. Notice that the index
%%* entry itself has no associated text.
%%*
%% 0, 300, Creating a Readme source file
%%*
%% 0, 25, Using David's Readme Compiler
%%*
%% 25, 0, Compiling the source file
To create a standalone guide, enter the command
RCOM <filename>
where <filename> is the name of the source file you
have created. RCOM will make a temporary file, and
will then bind it to README.BIN as a .EXE file with
the same name as the input file. That's all there
is to it!
%%*
%% 25, 0, Simplified Readmes
David's Readme Compiler allows you to create two types of
readme; the usual readme has full searching capabilities,
a number of extra formatting features, and enhanced print
facilities, including PostScript printing.
If the size of the final readme is critical, or you don't
need the extra capabilities, you can have DRC create a
simplified readme by using the -S switch on the command
line. A Simplified readme is about 10KB smaller than a
standard readme, but is much less capable.
Example: RCOM -s <filename>
Standard and simplified readmes can be created from the
same file - the syntax is common.
%%*
%% 25, 0, To clear or not to clear...
By default, DRC clears and paints the screen, but you can
force it to come up over the top of the current screen by
by invoking it with a /S switch: when it terminates, the
screen will be left as it was on entry. This is useful if
you want to use DRC to generate a help system which is
spawned by a parent program.
%%*
%% 25, 0, Running the compiled readme
Once you have compiled and bound your readme, you can use
it at once simply by typing its name.
%%*
%% 25, 0, Using the compiled readme
When your readme is running, the user will normally use it like
a simple menu-driven application. When the user hightlights an
option in a topic list and presses <Enter>, either another list
will appear, or the actual text of the entry. Pressing <Esc>
steps back to the previous list.
At any time the user can press <F10>, which will popup a menu
containing the options which are available at the time. From
a list, only the search options are ever available. From the
text of a topic, the search options and any others you have
enabled will be present in the menu. By default, options other
than the search options are disabled, but you can enable them
on a case-by-case basis, or globally, using the %%D operator
in the source file.
%%*
%% 25, 0, Searching for text
The user can search for text in the readme either by selecting
Find text from the option menu, or by pressing <F7>. The
search options cannot be disabled - they are always available.
The Find text operation always starts at the beginning of the
readme, while the Find again option starts after the last
find. A short-cut for Find again is the <F8> key.
Searches are case-insensitive - so NETWare is matched the same
as NetWare.
%%*
%% 25, 0, Printing a topic's text
If you have enabled printing on an option, then the user can
select Print from the options menu. A small dialog will
appear allowing the user to choose a printer port, and to
indicate whether the printer is a PostScript printer. The
values for each setting can be changed by pressing <Space>,
and the user can move between fields using the arrow keys.
DRC's printing is not fancy, but it's functional.
%%*
%% 25, 0, Editing a topic's text
If you have enabled editing for an option, then the user
can choose Edit from the options menu. If you have defined
an edit-mode screen using the %%E operator, it will appear
as soon as the choice is made.
DRC's editing facilities are not extensive, but they are
perfectly adequate for allowing a user to fill in an order
form or a questionnaire. While editing, the following
keys are available:
Arrows: move in the indicated direction
Ctrl-Arrows: move a word at a time
PgUp/PgDn: move a screen at a time
Tab: moves to the next field on the screen:
a field is anything starting with a
left square bracket ([). This feature
is handy for designing forms which the
user is to complete.
Ctrl-Y: delete the current line
Del, Bks: delete char right, delete char left
Ins: toggle insert mode (defaults to OFF)
%%*
%% 25, 0, Saving a topic's text
If you have enabled saving for an entry, this choice on
the option menu will allow the user to save the contents
of the current topic to a text file.
If editing is enabled, and the user has made changes to
the text, then the changes will also be saved into the
text file.
NOTE: The Save command does NOT allow the user to alter
the actual readme file itself.
%%*
%% 25, 0, A sample form
This is an example of DRC's forms capability: select
Edit from the <F10> menu, then press <Tab> to move
to the first field. Note that you got an instruction
screen when you selected Edit - a %%Edit_screen
keyword in the field defined that.
Try moving from field to field entering data and
editing the text. Don't worry, you can't alter the
actual readme file itself. Press <Tab> a few times.
Name: [ ]
Address: [ ]
Phone: [ ]
%%*
%%* Next, we have the first entry of type 100: this
%%* and the other type 100 entries will be displayed
%%* as a submenu when the index entry (above,
%%* "About the readme compiler") is chosen.
%%*
%% 100, 0, What the Readme compiler is...
It's a very rare PC software package indeed these days which
doesn't have a profusion of readme files associated with it.
Readme files can get lost, and it's not immediately intuitive
what you do with them. What's more, it's almost impossible to
create a Readme file which presents the necessary information
in an accessible way.
David's Readme Compiler attempts to provide a better way of
creating readme files. It's a set of programs which allow
you to create executable user guides - one program contains
it all, no need for extra files. You create a simple text
file which tells DRC how to present your guide, run it
through the compiler (RCOM.EXE), and violà! All done!
%%*
%% 100, 0, And what it can do ...
DRC allows you to "nest" text, effectively creating a
hierarchical menu structure. You can do this to an
arbitrarily deep level.
DRC supports colour, and allows printing and extracting
of text. You can highlight words in a message.
DRC has a search command which can look through a file
in a free-text form for keywords.
%% 100, 0, Then, some applications ...
You can use DRC for more than just readme files: here are
some ideas I've come up with.
On-line manuals for software.
Help systems, maybe for your LAN.
Presentations
Reference systems
... and so on. Pretty much anything which involves
organizing text for reference.
%%*
%% 100, 0, Licensing (good news!)...
The good news about DRC is that it is totally free. You
may use it in any way you wish, without restriction,
obligation, liability or responsibility. Commercial
organizations may distribute all, or any part of David's
Readme Compiler and derivatives with products if they wish.
The ONLY restrictions on David's Readme Compiler, are that
you may not sell it directly (although it's OK to include
it as part of another system) and you may not alter the
.BIN files in any way without explicit written permission
from the author.
If you would care to include a small credit in any readme
you create using DRC, I'd always be grateful, but I don't
even require this.
I hope you enjoy using DRC!
%%*
%% 100, 0, Some technical details...
DRC is written in C, using Borland C++ v3.1. It consists
of about 2,500 lines of C and Assembler for the actual
system, and another 12,000 lines for the user interface
code, which is a routine library (if you are familiar with
Pegasus Mail, you'll probably recognize much of the user
interface of DRC).
If would have been impossible to create DRC without the
help of the best editor ever written, Brief, by Solution
Systems.
%%*
%% 100, 0, And contacting the author.
DRC is written by David Harris, P.O. Box 5451, Dunedin,
New Zealand. If you have problems or questions, I can
be reached by e-mail as david@pmail.gen.nz (or from
CompuServe, >internet:david@pmail.gen.nz).
I can also be reached as david@otago.ac.nz.
Cheers!
-- David --
15 Aug '92
%%*
%% 300, 0, 94, 90, The sample file
The source file used to create this readme file
is supplied with the system as README.SRC.
You can refer to it to get a general feel for
how the source file needs to be prepared.
(Note, the horrible colours are deliberate!)
%% 300, 0, The general format
The source file for DRC is a single relatively simple
text file, which contains special markers to indicate
topics and section headings. Marker lines are always
introduced by two percentage signs (%%) at the start
of a line. Some marker lines require a character in
the third position - these are described in detail
in the next section.
Lines beginning with %%* are comments, and are ignored.
The other type of marker line is a topic heading: this
consists of 2 mandatory integers, 3 optional integers
and a title.
The first integer is a type field, which is simply
a numeric tag for the entry. A file can have several
entries with the same type number, which will make
up a menu. Type 0 entries are always the top-level
entries, and a file must have at least one of these.
The second integer is either 0, in which case the
entry has text which should be displayed when the
item is selected, or a positive value. If it is
the latter then it indicates that the entry is an
index for another type of entry: when the item is
chosen, DRC scans the file for all other entries
of the type specified and creates a sub-menu from
them, which it presents to the user.
The first two optional integers specify the video
attributes for text in a the window, and the window
frame respectively. A table of values is provided in
the menu (see Colour changes in Windows). You can
omit one or both of these, in which case DRC will
assume default values.
The third optional integer is a flags field, which
is a bit pattern describing the characteristics of
the topic, and the options which should be available
in the <F10> menu. This field is described in detail
later in this menu. You can set default flag values
which will apply to all topics with no explicit
flag field using a %%Default_flag keyword.
The title is displayed in the text window, and as
the choice in the menu.
Example: the line used to create the entry The Sample
File in this menu:
%% 300, 0, 94, 90, 6, The sample file
^ ^ ^ ^ ^ ^ ^─ The title
│ │ │ │ │ └──── Flags: (Save and Print only)
│ │ │ │ └──────── Frame colour (Lt Green/Magenta)
│ │ │ └──────────── Text colour (Yellow/Magenta)
│ │ └─────────────── Entry is not an index field
│ └─────────────────── The type for this entry
└─────────────────────── The marker line prefix
%%*
%% 300, 325, Keyword markers
%% 325, 0, Keyword markers
The marker lines described in this section have special
meanings in DRC: they are used to alter aspects of DRC's
behaviour, or to enable or disable special features.
DRC actually only examines the first letter of the key-
word, but you can use descriptive names for clarity,
provided they don't contain spaces or tabs.
%%*
%% 325, 0, %%* - Comment
Any line beginning with %%* is a comment, and is
ignored.
%%*
%% 325, 0, %%Title_bar
Use a %%Title_bar line to define a title bar for the
main screen. An optional integer can be included
which sets the video attribute of the title bar. For
a list of values, see the section Setting Colour in
Windows.
Example: %%Title_bar 31, Sample title bar
- defines a title bar in white on blue, with
the text "Sample title bar".
Only the last %%Title_bar option encountered in a
source file will be used.
%%*
%% 325, 0, %%Opening_screen
If you want to define a screen which is presented only
when the readme file is run, use a %%Opening_screen
keyword. This takes one mandatory integer value - the
ID of the screen to present. The screen is just a normal
topic like any other, except that no options are available.
The screen ID should be unique - there should be only
one topic in the file with the number you provide. If
there is more than one, DRC will use the first one it
encounters.
For performance reasons, the opening screen should be
declared early in the source file.
Example: Opening_screen 2000
- tells DRC to present the screen with the
ID tag 2000 at startup.
%%*
%% 325, 0, %%Status_line
This keyword declares a status line - text which DRC
will draw along the bottom of the screen. It takes one
mandatory integer parameter - the ID of the topic which
contains the text to display. The topic is just like any
other topic - you can set colours and other attributes.
The status line can be multi-line if you wish, but I
suggest you keep to one or two lines.
This is useful for a help line or a copyright notice.
%%*
%% 325, 0, %%Default_flags
Topics have a flag field which allows you to specify
border values for the window, and what options should
be available in the <F10> menu for the topic.
Use a %%Default_flags keyword to define a default flag
value for all successive topic definitions. The default
will be used for definitions without an explicit flag
field of their own. One integer parameter is required,
the value to use as a default. A full list of possible
flag field values is provided elsewhere in this guide.
You can use %%Default_flags repeatedly throughout the
source file. The value assigned lasts until either the
end of the source, or until another %%Default_flags
keyword is encountered.
%%*
%% 325, 0, %%Edit_screen
You can allow the user to edit screens in your readme
files. If you do, you may want to provide the user
with some help on the keys available while editing,
or other instructions: you can do this using this
keyword.
If an editing screen has been defined using this key-
word, DRC will present it when the user chooses Edit
from the <F10> menu. Once the user has closed the
edit screen, he or she can begin editing the text.
Only one %%Edit_screen can be declared in a file.
%%*
%% 300, 0, Flag fields for topics
The flag field for a topic controls what type of window
border DRC will use, and what features should be made
available in the <F10> menu. It is a bit pattern which
uses the following values:
Value │ Meaning
──────┼───────────────────────────────────────
1 │ The user may EDIT this topic
2 │ The user may PRINT this topic
4 │ The user may SAVE this topic
8 │ Draw NO border around the topic window
16 │ Draw a DOUBLE border around the window
32 │ Draw a THICK border around the window
Add these values to combine effects: so, to have a topic
which the user can EDIT and PRINT, with a thick border,
add 1 + 2 + 32 = 35.
%%*
%% 300, 0, Highlighting text
DRC automatically sizes the window for text according to
the maximum line width, and the number of lines. If there
are more lines than will fit in the Window, the user can
scroll using the arrow and page keys.
You can highlight text in a topic by enclosing it in ^A
characters (the IBM smiley face). You can reverse text
by enclosing it in ^B characters.
%% 300, 0, Colour changes in windows
The colour fields in entry headers are numeric values
which represent IBM screen attributes, according to
the following table:
Colour │ Text │ Background
─────────────────┼──────────┼───────────
Blue │ 1 │ add 16
Green │ 2 │ add 32
Cyan │ 3 │ add 48
Red │ 4 │ add 64
Magenta │ 5 │ add 80
Brown │ 6 │ add 96
Light grey │ 7 │ add 112
Dark grey │ 8 │ --na--
Light blue │ 9 │ --na--
Light green │ 10 │ --na--
Light cyan │ 11 │ --na--
Light red │ 12 │ --na--
Light magenta │ 13 │ --na--
Yellow │ 14 │ --na--
White │ 15 │ --na--
─────────────────┴──────────┴─────────
Example:
Yellow text on Magenta background
= 14 + 80
= 94
%% 300, 0, Colour changes in text
Colour changes in text are a little more tricky, and
may not work satisfactorily on monochrome systems.
To imbed a colour change, enter a ^C character in the
text, followed immediately by one of the following
characters:
A Blue text B Green text
C Cyan text D Red text
E Magenta text F Brown text
G Light grey text H Dark grey text
I Light Blue text J Light Green text
K Light Cyan text L Light Red text
M Light Magenta text N Yellow text
O Bright white text
Example: CCyan, DRed, NYellow, JLight-Green@
^C@ has a special meaning - it means "change to
whatever the original video colour was".
%%*
%% 300, 0, Limitations and notes
No single entry may be larger than about 16KB and
the file cannot at this stage have more than 640
total entries.
The source file MUST end with a single '%%' pair
on a line of its own.
If running under Novell NetWare, a guide compiled
with DRC must not be flagged Execute-only, although
it can be set to read only.
%%*
%% 0, 0, What's new in DRC v2.0
DRC v2.0 is a considerable enhancement over v1.0. The
following new features are provided:
Free-text searching (promised, but not delivered
in version 1.0)
Enhanced printing, including PostScript support
User can save the text of a topic to a file
User can edit the text of a topic
Forms mode input (using the <Tab> key
Options menu on <F10> replaces the <P>-Print
command of v1.0. You have control over which
options are made available on the menu.
Startup screen can be specified
Edit screen: a topic which DRC will present
when the user asks to edit a topic.
Status line - you can define text which DRC
will display along the bottom of the screen.
Control over window borders
Simplified readme support - the .BIN file from
DRC 1.0 is provided with this release, since
it generates readmes which are about 10KB
smaller than the default mode. Create a sim-
plified readme using the -S switch to RCOM.
%%*
%%* Note that the file MUST end with a blank '%%' pair.
%%
